Inside Macintosh: QuickTime Components
Sequence grabber components provide a full set of functions that allow your application to control the preview or record operation. You can use these functions to start and stop the operation, to pause data collection, and to retrieve a reference to the movie that is created during a record operation. This section describes these functions.
Use the SGStartPreview function to start a preview operation. The SGStartRecord function lets you start a record operation. The SGStop function allows you to stop a sequence grabber component.
You can instruct the sequence grabber to pause by calling the SGPause function. You can determine whether the sequence grabber is paused by calling the SGGetPause function.
You grant processing time to the sequence grabber by calling the SGIdle function. Be sure to call this function often during record and preview operations. If your application receives an update event during a record or preview operation, you should call the SGUpdate function.
You can prepare the sequence grabber for an upcoming preview or record operation by calling the SGPrepare function. This function also allows the sequence grabber to verify that it can support the parameters you have specified. By verifying the parameters you want to use, you can improve the startup of preview and record operations. Use the SGRelease function to release system resources after calling the SGPrepare function.
You can retrieve a reference to the movie created by a record operation by calling the SGGetMovie function. You can determine the resource ID value assigned to the last movie resource created by the sequence grabber by calling the SGGetLastMovieResID function.
You can extract a picture from the video source data by calling the SGGrabPict function.
The SGStartPreview function instructs the sequence grabber to begin processing data from its channels.
pascal ComponentResult SGStartPreview (SeqGrabComponent s);
The sequence grabber immediately presents the data to the user in the appropriate format, according to the channel configuration parameters you have specified (see "Working With Channel Characteristics," for information about configuring channels). Video data is displayed in the destination display region; sound data is played at the specified volume settings.
You stop the preview process by calling the SGStop function, which is described on SGStop .
In preview mode, the sequence grabber does not save any of the data it gathers from its channels. If you want to record the data, use record mode. You start a record operation by calling the SGStartRecord function, which is described in the next section.
The SGStartRecord function instructs the sequence grabber component to begin collecting data from its channels.
pascal ComponentResult SGStartRecord (SeqGrabComponent s);
The sequence grabber stores the collected data according to the recording parameters you specify with the SGSetDataOutput function, which is described on SGSetDataOutput . Before calling this function, you must correctly configure the sequence grabber's channels--see "Working With Channel Characteristics," for information about configuring sequence grabber channels.
You can switch from previewing to recording by calling this function during a preview operation--you need not stop the preview operation first. You stop the recording process by calling the SGStop function, which is described on SGStop .
You can cause the sequence grabber to display the data it obtains from its channels without storing any of the data by calling the SGStartPreview function, which is described in the previous section.
The SGIdle function provides processing time to the sequence grabber component and its channel components. After starting a preview or record operation, you should call this function as often as possible, until you stop the operation by calling SGStop .
If you do not call SGIdle frequently enough, you may lose data.
pascal ComponentResult SGIdle (SeqGrabComponent s);
The SGIdle function reports several status and error conditions by means of its result code. If you have established a time limit for a record operation by calling the SGSetMaximumRecordTime function (described on SGSetMaximumRecordTime ), SGIdle returns a result code of grabTimeComplete when the time limit expires. In addition, SGIdle reports errors that are specific to the channels that are active for a given operation. If SGIdle returns a nonzero result code during a record operation, you should still call the SGStop function (described on SGStop ) so that the sequence grabber can store the data it has collected.
The SGUpdate function allows you to tell the sequence grabber that it must refresh its display.
pascal ComponentResult SGUpdate (SeqGrabComponent s,
RgnHandle updateRgn);
SGUpdate (theSG, ((WindowPeek)updateWindow)->updateRgn);
You may use the SGUpdate function to tell the sequence grabber that it must refresh its display. You should call this function whenever you receive an update event for a window that contains a sequence grabber display. You should call this function before calling the Window Manager's BeginUpdate function.
Your application should avoid drawing where the sequence grabber is displaying video. Doing so may cause some video digitizer components to stop displaying video.
The SGStop function stops a preview or record operation.
pascal ComponentResult SGStop (SeqGrabComponent s);
The sequence grabber releases any system resources it used during the operation, such as temporary memory. In the case of a record operation, the sequence grabber stores the collected movie data in the assigned movie file--you specify the movie file by calling the SGSetDataOutput function, which is described on SGSetDataOutput .
You can suspend or restart a record or preview operation by calling the SGPause function. You supply a byte value that instructs the sequence grabber whether to pause or restart the current operation.
pascal ComponentResult SGPause (SeqGrabComponent s,
Byte pause);
The SGPause function does not release any system resources or temporary memory associated with the current operation. Consequently, it is generally much faster than using the SGStop and SGStartRecord functions or the SGStartPreview function to suspend an operation.
When you restart the operation, the sequence grabber component may be unable to satisfy your request. This can occur, for example, if the user has moved the display window to a location that the digitizing hardware cannot support.
You can determine whether the sequence grabber is paused by calling the SGGetPause function.
pascal ComponentResult SGGetPause (SeqGrabComponent s,
Byte *paused);
The SGPrepare function instructs the sequence grabber to get ready to begin a preview or record operation (or to commence both operations). You specify the operations.
pascal ComponentResult SGPrepare (SeqGrabComponent s,
Boolean prepareForPreview,
Boolean prepareForRecord);
The sequence grabber component does whatever is necessary to get ready to start the preview or record operation. This may involve allocating memory, readying hardware, and notifying the sequence grabber's channels. By calling this function, you ensure that the SGStartRecord or SGStartPreview function starts as quickly as possible.
If you do not call this function before starting a record or preview operation, the sequence grabber component makes these preparations when you start the operation. You cannot call this function after you start a preview or record operation.
If you call SGPrepare without subsequently starting a record or preview operation, you should call the SGRelease function (described in the next section). This allows the sequence grabber component to release any system resources it allocated when you called SGPrepare .
The window in which the sequence grabber is to draw video frames (as defined by the SGSetGWorld function, described on SGSetGWorld ) must be visible before you call the SGPrepare function. Otherwise, the sequence grabber does not display the frames properly. If the window isn't visible and SGPrepare is called with the prepareForPreview parameter set to true and the prepareForRecord parameter set to false , and the window is subsequently shown via the Window Manager's ShowWindow routine, the sequence grabber won't display frames properly in the video window. The visible region of the window wasn't valid when the SGPrepare call was made.
The SGRelease function instructs the sequence grabber to release any system resources it allocated when you called the SGPrepare function, which is described in the previous section. You should call SGRelease whenever you call SGPrepare without subsequently starting a record or preview operation.
pascal ComponentResult SGRelease (SeqGrabComponent s);
When you stop a record or preview operation by calling the SGStop function, the sequence grabber component automatically releases the resources it uses during the operation. Consequently, you do not have to call this function after a record or preview operation.
You cannot call the SGRelease function during a record or preview operation.
The SGGetMovie function returns a reference to the movie that contains the data collected during a record operation. You can use this movie identifier with Movie Toolbox functions. However, you should not dispose of this movie--it is owned by the sequence grabber component. Furthermore, the sequence grabber component disposes of this movie when you prepare for or start the next record or preview operation, or when you close the connection to the sequence grabber. If you want to work with a movie containing the collected data, use the Movie Toolbox's NewMovieFromFile function (see the chapter "Movie Toolbox" in Inside Macintosh: QuickTime for more information).
You can call this function only after you have stopped the record operation by calling the SGStop function.
pascal Movie SGGetMovie (SeqGrabComponent s);
The SGGetMovie function returns a reference to the movie that contains the data collected during a record operation. If there is no current movie, either because you are in preview mode or because you have not yet stopped the record operation, the sequence grabber component sets this returned reference to nil .
The SGGetLastMovieResID allows you to retrieve the last resource ID used by the sequence grabber component. The sequence grabber component assigns a new resource ID to each movie resource it creates. The sequence grabber creates the movie resource when you stop a record operation by calling the SGStop function, unless you have instructed the sequence grabber not to add the movie resource to the movie file (see the description of the SGSetDataOutput function beginning on SGSetDataOutput for more information).
pascal ComponentResult SGGetLastMovieResID (SeqGrabComponent s,
short *resID) ;
The SGGrabPict function provides a simple interface that allows your application to obtain a QuickDraw picture from a sequence grabber component. The sequence grabber can display the picture directly, or it can write the picture to an offscreen buffer. This function is limited in scope, however, and does not allow you to control all of the parameters that govern the operation. When you call this function, the sequence grabber component obtains and configures appropriate sequence grabber channel components (if necessary), grabs the data, and then releases any components it obtained.
pascal ComponentResult SGGrabPict (SeqGrabComponent s,
PicHandle *p,
const Rect *bounds,
short offscreenDepth,
long grabPictFlags);
If you have created any channels for the sequence grabber component, the SGGrabPict function uses those channels to obtain the data for the captured image.